RubyLLM phased migration feature-flagged - #775

What

Phases 1–6 of the RubyLLM migration plan — a feature-flagged migration from three per-provider SDK gems (ruby-openai, ruby-anthropic, gemini-ai) to the unified ruby_llm gem. Phases 1–5 land the new backend behind a flag; Phase 6 flips the flag on by default outside the test environment. Each commit maps to one plan phase; they can be split into separate PRs later if narrower review is desired.

Phase 1 — Scaffolding (406b850)

• Adds ruby_llm ~> 1.16.0 (patchlocked; existing SDK gems untouched)
• Adds use_ruby_llm feature flag (off by default) and initializer with intentional dummy keys
• Empty AIBackend::RubyLLM shell with supports_driver? → false
• APIService#ai_backend guard routes through RubyLLM only when flag is on AND driver is supported
• Fixes latent bug where preference writes clobbered unrelated keys (now deep-merges)

Phase 2 — OpenAI text-only chat (a04415c)

• supports_driver? returns true for openai only
• get_oneoff_message / stream_next_conversation_message full overrides on RubyLLM's Chat API
• stream_handler yields chunks, captures tokens, maps RubyLLM errors to ConfigurationError/RateLimitError
• Text-only preceding_conversation_messages, tool messages skipped
• Groq (openai driver, non-canonical URL) via openai_api_base override
• Full TestClient::RubyLLM::Chat fake

Phase 3 — Anthropic + Gemini text chat (2c917bc)

• supports_driver? now true for all three drivers
• provider_slug / dynamic ruby_llm_context / provider_for_url for per-provider routing and test_execute
• Anthropic + Gemini streaming and job-level tests

Phase 4 — Image/PDF attachment parity (98d5187)

• Multimodal input via RubyLLM::Content.new(text, attachments) with RubyLLM::Attachment (ActiveStorage-native)
• PDFs inlined as extracted text via document.extract_pdf_text (no native PDF upload)
• sanitize_content strips json_of_generated_image on replay
• Per-driver vision streaming, PDF extraction, mixed image+text, and sanitization tests

Phase 4.5 — Tool-interception pre-check (c478d05)

• InterceptedTool < ::RubyLLM::Tool, registered per Toolbox tool, whose execute raises ToolCallIntercepted
• Halts RubyLLM's automatic tool-execution loop so HostedGPT can execute tools itself in Phase 5 — RubyLLM never runs a tool or auto-continues
• name/description/params_schema stored explicitly (the base class derives name from the class name, collapsing all tools into one entry)
• tool_interception_test.rb asserts the halt against the pinlocked gem behavior

Phase 5 — Tool/function calling parity (1591e82)

• stream_next_conversation_message extracts content_tool_calls and formats them via format_tool_calls for downstream GetNextAIMessageJob handling
• tool_instances maps Toolbox.tools (OpenAI-format descriptors) to InterceptedTool instances — no schema re-derivation
• InterceptedChat#handle_tool_calls (private override) raises ToolCallIntercepted for any tool call, closing the unknown/hallucinated-name gap that InterceptedTool alone could not halt; InterceptedTool#execute kept as a safety net against upstream rename
• get_oneoff_message widened with a json: kwarg for the provider-blind autotitle path (appends a JSON-coercion instruction, not raw response_format:, which 400s on Anthropic)
• Error contract conforms to the unified, provider-blind standard: ConfigurationError < AIBackend::ConfigurationError, RATE_LIMIT_ERRORS → Faraday::TooManyRequestsError (mapped at the chat.complete boundary), RateLimitError dropped
• Groq tool held via instance-level tools_enabled? (URL check) since the class-level supports_tools? gate is bypassed when the flag is on
• Tests: unit (ruby_llm_test.rb), get_next_ai_message_job_ruby_llm_test.rb, new autotitle_conversation_job_ruby_llm_test.rb, interception specs, and tool-call simulation in TestClient::RubyLLM::Chat

Phase 6 — Flip default on, with a test-env carve-out (eaaa250)

• Flips use_ruby_llm default on for every non-test environment via hand-rolled ERB (ENV["USE_RUBY_LLM_FEATURE"] || (Rails.env.test? ? "false" : "true")); the test environment stays off so the legacy SDK suite keeps dispatching to the old backends
• Escape hatches preserved: USE_RUBY_LLM_FEATURE=false, or a per-user preferences[:feature][:use_ruby_llm] = false
• feature_test.rb updated to pin the env-dependent test-env default (boolean false) plus the user-preference override
• Optional Toolbox::Image image-generation migration to RubyLLM.context.paint was intentionally skipped — image generation continues through the existing OpenAI delegation
• No job changes (the unified, provider-blind rescues from Phases 1–5 already handle the RubyLLM error contract)

Not in this PR

No existing backends, tests, or gems are modified. Image generation still runs through the existing OpenAI client path (the optional Phase 6 RubyLLM.context.paint migration was skipped). The old backends, old gems, old test clients, the supports_driver? guard, and the flag itself are removed in Phase 7, which ships as a separate PR (gated on production dogfood signal from Phase 6).

Testing

bin/rails test — 892 runs, 0 failures, 0 errors. New RubyLLM tests opt in via stub_features(use_ruby_llm: true). The test-environment default stays false (the Phase 6 carve-out), so the legacy SDK tests keep dispatching to the old backends and the suite stays green. Non-test environments now route through RubyLLM by default; the plan's remaining dogfood checks (text/images/PDFs/tools/autotitle/cancellation/rate-limit/blank-response parity across all three providers) are manual criteria to confirm before merge and before Phase 7.